home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 March / EnigmA AMIGA RUN 05 (1996)(G.R. Edizioni)(IT)[!][issue 1996-03][Skylink CD IV].iso / earcd / program / explorer.lzh / explorer.doc < prev    next >
Text File  |  1995-12-20  |  7KB  |  149 lines
  1. Short: Amazing System Explorer/Debugger
  2. Type: dev/e
  3. Author: jason@fsel.com (Jason R. Hulance)
  4. Uploader: jason@fsel.com (Jason R. Hulance)
  5.  
  6. Explorer 1.0j
  7. =============
  8.  
  9. Allows you to browse around memory as E objects (which are like C structs).
  10.  
  11. (The complete distribution of Amiga E [but with a demo compiler] is
  12. available from Aminet, in dev/e.  The current version is amigae32a.lha and
  13. amigae32a_extras.lha, with a v3.2e update patch also available.)
  14.  
  15. Basic function
  16. --------------
  17. You can enter an address and then select the object which is (supposed to
  18. be?) at that address.  You can then see the value that each element of the
  19. object contains and follow pointers etc. by double-clicking on the element
  20. (a single click changes the address to the element's address, which is an
  21. offset from the object address you specified).  A double-click may
  22. therefore change the object being browsed, so there is a way of returning
  23. to the original object via the "Back Up" button.
  24.  
  25. The list of objects is created by scanning all the modules in the
  26. 'Emodules:' directory and its sub-directories, so you can include your own
  27. objects by putting suitable modules in a sub-directory called, say,
  28. 'mymods'.
  29.  
  30. The address and object can also be specified via ARexx, making Explorer an
  31. extremely useful debugging tool as well as a system browser!
  32.  
  33. Object layout
  34. -------------
  35. The elements of the selected object are listed in order.  If you choose to
  36. see the value of element it will be displayed in hex in parenthesis after
  37. the element, and if you choose to see the element address (an offset from
  38. the object address) it will be displayed after an '@'.  (Use the "Elements"
  39. menu to select which you want to see -- the default is just the value.)
  40.  
  41. Where to start
  42. --------------
  43. The buttons on the bottom of the GUI give some interesting starting points:
  44.  
  45. 1) "Exec."  Views the address stored in the 'execbase' global variable as
  46.    an 'execbase' object.  The exec.library is the most fundamental Amiga
  47.    system library, and 'execbase' is its corresponding library base object.
  48. 2) "Graphics."  Same as 1) but for the 'gfxbase' variable and object for
  49.    the graphics.library.
  50. 3) "Intuition."  Same as 1) but for the 'intuitionbase' variable and object
  51.    for the intuition.library.
  52. 4) "This Process."  Views the 'process' object for the running Explorer
  53.    program!
  54.  
  55. Simple types
  56. ------------
  57.  
  58. The "CHAR", "INT" and "LONG" buttons view the contents of the address as if
  59. it were a pointer to the corresponding type, and fills in the 'Hex:',
  60. 'Decimal:' and 'String:' texts with the value(s) being pointed at.  (If you
  61. double-click on an element of an object with one of these types [or PTR TO
  62. them] then this is done automatically.  The contents of the PTR or LONG
  63. value are also copied to the current address to make following arrays
  64. etc. easier.)
  65.  
  66. "BSTR" is similar to "CHAR" but it first converts the address from a BCPL
  67. pointer and then skips over the length byte.  "BADDR" just converts the
  68. address to a BCPL pointer.
  69.  
  70. "Prev" and "Next" treat the address as pointing to an array of the type
  71. last requested (i.e., an object or simple type).  "Prev" moves the address
  72. back to the previous element in the array, and "Next" moves it on to the
  73. next.
  74.  
  75. ARexx
  76. -----
  77. The "Reply" button manually replies to an ARexx message that may have been
  78. received.  You can also let Explorer automatically reply to these messages
  79. by selecting the option under the ARexx menu, but the manual method is best
  80. since you can be sure that the pointers remain valid while you browse
  81. (since the calling program is halted).  Once you've replied to a message
  82. the calling program is free to scribble all over the memory it just pointed
  83. you at.
  84.  
  85. A module 'sendexplorer.m' is supplied to simplify the debugging aspect of
  86. Explorer.  It defines a single function, 'sendExplorer', which you call
  87. with the address and object name you are interested in.  The third,
  88. optional parameter is a message port for replies.  If you don't supply this
  89. then a temporary port is created for the duration of the function call.
  90. (The purpose of this parameter is to allow you to re-use the same port
  91. during your program if you call 'sendExplorer' a lot.)  An example call is:
  92.  
  93.   sendExplorer(packet, 'dospacket')
  94.  
  95. Example program
  96. ---------------
  97. To show how useful Explorer can be, there is a modified version of the
  98. 'empty' handler supplied.  This uses the above call to 'sendExplorer' to
  99. communicate the value of the packet currently being processed.  Since the
  100. handler is not a full process there would normally be no simple way of
  101. debugging it or examining the packets as they arrive (none of the DOS
  102. functions, such as printing text, are available to it).  But it can send
  103. messages to ARexx and thus to Explorer.
  104.  
  105. To try it out:
  106.  
  107.  1) Make sure ARexx is up (by running RexxMast, if necessary).
  108.  2) Start up Explorer using,
  109.       run explorer
  110.  3) Now copy 'empty-handler' to L:,
  111.       copy empty-handler L:
  112.  4) Mount it using,
  113.       mount empty: from empty.mountlist
  114.  5) Use the handler,
  115.       type empty:10
  116.  6) Look at Explorer.  It will be displaying the first packet. Browse
  117.     around it, remembering that most elements will be BCPL strings.
  118.  7) Press "Reply" to reply to this message.
  119.  8) Another packet arrives and the message is sent to Explorer.
  120.  9) Repeat 6)-8) until the 'type' command finishes and you get the Shell
  121.     prompt back.
  122.  
  123. Legal stuff
  124. -----------
  125. The programs and modules in this archive are all
  126. Copyright (C) 1995, Jason R. Hulance.
  127.  
  128. You are free to use the modules in your programs, whether they are freeware
  129. or commercial.  However, if you want to distribute any of this archive you
  130. must include it all, unmodified, together with this file.
  131.  
  132. And as the good man Wouter puts it: "No guarantees, no warranty.  If you
  133. manage to drown your pet goldfish using Explorer, or Explorer fails to be
  134. suitable for ordering pizzas, that's entirely your problem.  Whatever
  135. happens, don't blame it on me."
  136.  
  137. Wouter-ware
  138. -----------
  139. In spite of the above, this product is also Wouter-ware.  Wouter (van
  140. Oortmerssen) is the author of Amiga E, the language which makes these
  141. things possible.  If you find Explorer really useful and would like to show
  142. your appreciation then please register your Amiga E.  We all need to
  143. encourage the real stars like Wouter to continue their great work on the
  144. Amiga.
  145.  
  146. Once again, the complete distribution of Amiga E (with a demo compiler) is
  147. available from Aminet, in dev/e.  The current version is amigae32a.lha and
  148. amigae32a_extras.lha, with a v3.2e update patch also available.
  149.